package com.dana1.nos;

import java.io.Serializable;
import java.util.ConcurrentModificationException;
import java.util.Iterator;

/**
 * Defines a storage endpoint.
 * @author Dana
 */
public interface Storage {
	// this is the new and improved optimistic replacement for ObjectService

	/**
	 * Retrieves an identifiable object 
	 * @param c the class of the object being retrieved
	 * @param identifier the identifier for the object
	 * @param consistently if true, then the system should make its best effort to return the latest valid copy.
	 */
	public <T extends Serializable> T get(Class<T> c, String identifier);
	/**
	 * Retrieves one or more identifiable objects matching a given identifier prefix.
	 * @param c the class of the object being retrieved
	 * @param identifier the prefix of the identifiers for the objects
	 * @param consistently if true, then the system should make its best effort to return the latest valid copy.
	 */
	public <T extends Serializable> Iterator<T> getByPrefix(Class<T> c, String identifier);
	/**
	 * Inserts or updates an identifiable object with the given identifier.
	 * @param identifier (optional for update mode)
	 * @param obj Either an object previously retrieved by the get method, or a new object.
	 * @throws ConcurrentModificationException if the object being updated or inserted already exists, and/or if the object has been modified by someone else since it was last retrieved 
	 */
	public <T extends Serializable> void put(String identifier, T obj) throws ConcurrentModificationException;
	/**
	 * Removes an existing object
	 * @param obj An object previousl retrieved by the get method.
	 * @throws ConcurrentModificationException if the object being removed has been modified by someone else since it was last retrieved, or is no longer present in the system
	 */
	public <T extends Serializable> void remove(T obj) throws ConcurrentModificationException;
}
